home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1997 February: Technology Seed / Mac Tech Seed Feb '97.toast / OpenDoc 1.2b2c1 / OpenDoc / OpenDoc Utilities / Interfaces / DocUtils.h < prev    next >
Encoding:
C/C++ Source or Header  |  1997-01-01  |  15.8 KB  |  358 lines  |  [TEXT/MPS ]
  1. /*
  2.     File:        DocUtils.h
  3.  
  4.     Contains:    Interface to high level UI oriented document utilities
  5.  
  6.     Owned by:    Nick Pilch
  7.  
  8.     Copyright:    © 1995 - 1996 by Apple Computer, Inc., all rights reserved.
  9.  
  10.     Change History (most recent first):
  11.  
  12.          <5>    20.09.1996    NP        1386083: removed routines
  13.          <4>    11.09.1996    NP        additional comments/fixed header
  14.          <2>     7/11/96    TJ        Added ODClearIsUnsavedNewDocument
  15.  
  16.     These functions are a collection of utilities which are used by the OpenDoc
  17.     Shell and other subsystems to manipulate user documents.
  18.     
  19.     They will also be useful to part editors which manipulate documents directly,
  20.     e.g. if a part editor wants to open another document in its process,
  21.     or create a new document from part/document stationery.
  22.     
  23.     The functions also help container part editors implement the "Insert…"
  24.     Document menu item.
  25.     
  26.     To Do:
  27.     
  28.         Reorder functions hilevel first, lowlevel last.
  29.         Move NewDocument from Shell to here.
  30. */
  31.  
  32. #ifndef _DOCUTILS_
  33. #define _DOCUTILS_
  34.  
  35. // for ODFileRefNum
  36. #ifndef _PLFMFILE_
  37. #include "PlfmFile.h"
  38. #endif
  39.  
  40. #ifndef SOM_ODWindow_xh
  41. #include "Window.xh"
  42. #endif
  43.  
  44. //==============================================================================
  45. // Classes used by this interface
  46. //==============================================================================
  47.  
  48. class Environment;
  49. class ODSession;
  50.  
  51. class ODPart;
  52.  
  53. class ODStorageUnit;
  54. class ODDraft;
  55. class ODDocument;
  56. class ODContainer;
  57. class PlatformFile;
  58.  
  59. //==============================================================================
  60. // MACROS
  61. //==============================================================================
  62.  
  63. #define RETURN_IF_NULL(x,y)    if (!(x)) return y;
  64. #define HAS_WRITE_ACCESS(x) ((x) >= kODDPSharedWrite)
  65.  
  66. extern "C" {
  67.  
  68. //==============================================================================
  69. // Opening an file/container/document/draft
  70. //==============================================================================
  71.  
  72. //------------------------------------------------------------------------------
  73. // ODAcquireCtrDocTopDraft
  74. //    Given a PlatformFile object, get the container, document and top draft (readonly)
  75. //  reget the draft if you need more permissions.
  76. //------------------------------------------------------------------------------
  77.  
  78. void ODAcquireCtrDocTopDraft(Environment* ev, ODSession* session, PlatformFile* file, 
  79.         ODContainer** container, ODDocument** document, ODDraft** draft);
  80.                 
  81. //------------------------------------------------------------------------------
  82. // ODGetNthOpenDocument
  83. //    A pointer to the nth document in the collection of open documents is returned.
  84. //    If the collection is empty, then kODNULL is returned.
  85. //    It is the caller's responsibility to Acquire the returned document it she wishes to 
  86. //    hold onto it.
  87. //------------------------------------------------------------------------------
  88.  
  89. ODDocument*    ODGetNthOpenDocument(Environment* ev, ODSession* session, ODULong n);
  90.                                 
  91. //------------------------------------------------------------------------------
  92. // ODGetOpenDocumentFromRefNum
  93. //    Given a refnum, if it refers to a document open in this process, then a pointer to
  94. //    the respective ODDocument object is returned, else kODNULL is returned.
  95. //    It is the caller's responsibility to Acquire the returned document it she wishes to 
  96. //    hold onto it.
  97. //------------------------------------------------------------------------------
  98.  
  99. ODDocument*    ODGetOpenDocumentFromRefNum(Environment* ev, ODSession* session,
  100.                 ODFileRefNum refnum);
  101.  
  102. //------------------------------------------------------------------------------
  103. // ODGetTempDraftFromOpenDocument
  104. //    Given a pointer to an already open ODDocument which has a tempdraft with rw perms,
  105. //    a pointer to that tempdraft is returned.  
  106. //    If there no tempdraft is found then kODNULL is returned.
  107. //    It is the caller's responsibility to Acquire the returned tempdraft it she wishes to 
  108. //    hold onto it.
  109. //------------------------------------------------------------------------------
  110.  
  111. ODDraft*    ODGetTempDraftFromOpenDocument(Environment* ev, ODSession* session,
  112.                 ODDocument* document);
  113.  
  114. //------------------------------------------------------------------------------
  115. // ODTempDraftCreated
  116. //    This method updates the appropriate internal namespaces to note that a 
  117. //    tempdraft has been created and opened on the document passed in.
  118. //  The caller is responsible for properly refcounting the tempdraft.
  119. //------------------------------------------------------------------------------
  120.  
  121. void    ODTempDraftCreated(Environment* ev, ODSession* session, 
  122.             ODDocument* document, ODDraft* tempDraft);
  123.  
  124. //------------------------------------------------------------------------------
  125. // ODDocumentOpened
  126. //    This method updates the appropriate internal namespaces to note that an ODDocument
  127. //    has been opened with the given file refnum.  If a tempdraft was created and opened
  128. //    with rw perms, then that should also be passed in, else pass in kODNULL.
  129. //    This method bumps the refcount of document and its container in order to keep a valid
  130. //    reference to it.  The caller is responsible for properly refcounting the tempdraft.
  131. //    This function calls ODTempDraftCreated as part of its implementation;
  132. //    no need to also call ODTempDraftCreated if you call this function.
  133. //------------------------------------------------------------------------------
  134.                 
  135. void        ODDocumentOpened(Environment* ev, ODSession* session,
  136.                 ODFileRefNum refnum, ODDocument* document, ODDraft* tempDraft);
  137.                 
  138. //==============================================================================
  139. // Document Properties
  140. //==============================================================================
  141.  
  142. //------------------------------------------------------------------------------
  143. // ODResetDateModByInfo
  144. //  Use this call when creating a new draft, either a new docuemnt from stationery,
  145. //    or a new saved draft.
  146. //  If it's a new document, then after calling SetBaseDraftFromForeignDraft on the new document,
  147. //  you need to reset the creation date, modification date, modification by (username) info
  148. //  since the person who created the new document may not necessarily be the same person
  149. //  who created the stationery.
  150. //------------------------------------------------------------------------------
  151.  
  152. void ODResetDateModByInfo(Environment* ev, ODStorageUnit* su);
  153.  
  154. //------------------------------------------------------------------------------
  155. // ODGetDocumentFileName
  156. //    Use this call to retrieve the name of the file of the document.
  157. //    fileName is presumed to be preallocated array of 256 characters.
  158. //    Maximum length of fileName filled in is 255 characters (256th reserved for
  159. //  terminating null).
  160. //------------------------------------------------------------------------------
  161.  
  162. void ODGetDocumentFileName(Environment* ev, ODDocument* document, char* fileName);
  163.  
  164. //==============================================================================
  165. // Root Part/StorageUnit/Draft
  166. //==============================================================================
  167.  
  168. //------------------------------------------------------------------------------
  169. // ODAcquireRootPartOfDraft
  170. //  Given a draft object, get the root part
  171. //------------------------------------------------------------------------------
  172.  
  173. ODPart* ODAcquireRootPartOfDraft(Environment* ev, ODDraft* draft);
  174.  
  175. //------------------------------------------------------------------------------
  176. // ODAcquireRootPartSUOfDraft
  177. //  Given a draft object, get the root part's storageUnit without getting the part
  178. //------------------------------------------------------------------------------
  179.  
  180. ODStorageUnit* ODAcquireRootPartSUOfDraft(Environment* ev, ODDraft* draft);
  181.  
  182. //------------------------------------------------------------------------------
  183. // ODSetRootPartOfDraft
  184. //  Given a draft object and the storageUnit of a part, set that part to be
  185. //  the root part of the draft.
  186. //  Preconditions:
  187. //        Write permissions on the draft.
  188. //        No current root part in the draft*.
  189. //
  190. // *Calling this function when there already is a root part, not represented by the
  191. // rootPartSU passed in, will cause data loss in the document.
  192. //------------------------------------------------------------------------------
  193.  
  194. void ODSetRootPartSUOfDraft(Environment* ev, ODDraft* draft, ODStorageUnit* rootPartSU);
  195.  
  196. //------------------------------------------------------------------------------
  197. // ODGetDraftOfWindow
  198. //  Given a window object, get the root part's storageUnit's draft
  199. //------------------------------------------------------------------------------
  200.  
  201. ODDraft* ODGetDraftOfWindow(Environment* ev, ODWindow* window);
  202.  
  203.  
  204. //==============================================================================
  205. // Active/Changed Utils
  206. //==============================================================================
  207.  
  208. ODWindow*    ODAcquireActiveWindow(Environment* ev, ODSession* session);
  209. ODDraft*    ODGetActiveDraft(Environment* ev, ODSession* session);
  210. ODDocument*    ODGetActiveDocument(Environment* ev, ODSession* session);
  211.  
  212. ODBoolean    ODDocumentHasChanges(Environment* ev, ODSession* session,
  213.                 ODDocument* document);
  214. ODBoolean    ODDocumentHasWriteAccess(Environment* ev, ODSession* session,
  215.                 ODDocument* document);
  216. ODBoolean    ODDraftHasWriteAccess(Environment* ev, ODDraft* draft);
  217.  
  218. //==============================================================================
  219. // User level document operations
  220. //==============================================================================
  221.  
  222. //------------------------------------------------------------------------------
  223. // ODNewDocument
  224. //  Given a valid container, this function turns it into a valid New OpenDoc document
  225. //    By creating a root part with the editor and/or kind passed inCreates a new document
  226. //    It is the caller's responsibility to make sure that the container can be written to.
  227. //------------------------------------------------------------------------------
  228.  
  229. void ODNewDocument(Environment* ev, ODContainer* container,
  230.                             ODType        rootPartKind,
  231.                             ODEditor    rootPartEditor);
  232.  
  233. //------------------------------------------------------------------------------
  234. // ODIsUnsavedNewDocument
  235. //  Returns whether or not the document has been saved since it was created.
  236. //------------------------------------------------------------------------------
  237.  
  238. ODBoolean ODIsUnsavedNewDocument(Environment* ev, ODSession* session, ODDocument* document);
  239.  
  240. //------------------------------------------------------------------------------
  241. // ODSetIsUnsavedNewDocument
  242. //  Sets the fact that the document has not been saved since it was created.
  243. //------------------------------------------------------------------------------
  244.  
  245. void ODSetIsUnsavedNewDocument(Environment* ev, ODDraft* draft);
  246.  
  247. //------------------------------------------------------------------------------
  248. // ODClearIsUnsavedNewDocument
  249. //  Clears the fact that the document has not been saved since it was created.
  250. //------------------------------------------------------------------------------
  251.  
  252. void ODClearIsUnsavedNewDocument(Environment* ev, ODDraft* draft);
  253.  
  254. //------------------------------------------------------------------------------
  255. // ODOpenFileDocument
  256. //    Opens the document specified in the passed in file.
  257. //    If write permissions are requested (and possible), then a tempdraft is
  258. //    created, otherwise the document is opened readonly.
  259. //    This method calls ODDocumentOpened appropriately.
  260. //  The "current" draft is returned, all ready to be sent into an ODOpenDraft
  261. //    call.
  262. //    Note that if a tempdraft was created, that is what is returned as the
  263. //    "current" draft.
  264. //    The draft returned is a refcounted reference that the caller owns.
  265. //    
  266. //------------------------------------------------------------------------------
  267.  
  268. ODDraft* ODOpenFileDocument(Environment* ev, ODSession* session, PlatformFile* file,
  269.             ODDraftPermissions permissions);
  270.  
  271. //------------------------------------------------------------------------------
  272. // ODOpenDraft
  273. //    Notifies all appropriate objects that this draft is opening.
  274. //    The draft's document must have already been opened with ODOpenDocument.
  275. //  E.g. the LinkManager, Undo, Clipboard, WindowState (opens windows on that
  276. //    draft) etc.
  277. //  The draft is not acquired, nor is it added to the tempdrafts collection.
  278. //
  279. //    This function is also called to bring the windows of a particular document
  280. //    to the front of a process when the user double-clicks on a file in the
  281. //    Finder.
  282. //------------------------------------------------------------------------------
  283.  
  284. void ODOpenDraft(Environment* ev, ODSession* session, ODDraft* draft);
  285.  
  286. //------------------------------------------------------------------------------
  287. // ODCloseDraft
  288. //    Notifies all appropriate objects that this draft is closing.
  289. //  E.g. the LinkManager, Undo, Clipboard, WindowState (closes windows on that draft) etc.
  290. //  The draft is not released, nor is it removed from the tempdrafts collection. 
  291. //------------------------------------------------------------------------------
  292.  
  293. void ODCloseDraft(Environment* ev, ODSession* session, ODDraft* draft);
  294.  
  295. //------------------------------------------------------------------------------
  296. // ODCloseDocument
  297. //    Closes the document and any associated windows etc.
  298. //    Caller is responsible for saving changes, prompting the user etc. BEFORE calling.
  299. //    Document is released.
  300. //    It is removed from the list of open documents, and if it has a tempdraft,
  301. //    that too is removed from the tempdrafts collection.
  302. //    Removes any tempdraft and any changes therein which implicitly releases the tempdraft.
  303. //    If there are no more open windows once the document is closed,
  304. //    then kODTrue is returned.
  305. //------------------------------------------------------------------------------
  306.  
  307. ODBoolean ODCloseDocument(Environment* ev, ODSession* session, ODDocument* document);
  308.  
  309. //------------------------------------------------------------------------------
  310. // ODReleaseCloseWindow
  311. //    Releases the window and
  312. //    Closes the window and any dependent windows.
  313. //    All child windows are dependent on the root windows of their draft.
  314. //    All windows of a saved draft of a document are dependent on the root windows 
  315. //    of the "current/top/temp" draft of the document.
  316. //    If the last window of a document is closed, then ODCloseDocument is called.
  317. //    If there are no more open windows once the window is closed,
  318. //    then kODTrue is returned.
  319. //    This function MUST consume the window reference passed in because:
  320. //    1. The Windowstate hangs onto a reference to every window
  321. //    2. The window's frame hangs onto a reference to the window
  322. //    2. The window passed in is AT LEAST the third reference to that window
  323. //    3. If the window is that last root window of the draft,
  324. //       then the window MUST be fully released by this function so that
  325. //       the draft, document and container can be properly released by ODCloseDocument
  326. //       which as noted above, is called by this function.
  327. //------------------------------------------------------------------------------
  328.  
  329. ODBoolean ODReleaseCloseWindow(Environment* ev, ODSession* session, ODWindow* window);
  330.  
  331. //------------------------------------------------------------------------------
  332. // ODSaveDocument
  333. //    Saves the document if there is an associated tempdraft.  Otherwise does nothing.
  334. //------------------------------------------------------------------------------
  335.  
  336. void ODSaveDocument(Environment* ev, ODSession* session, ODDocument* document);
  337.  
  338. //------------------------------------------------------------------------------
  339. // ODSaveACopyOfDraft
  340. //    Saves a copy of the draft.
  341. //    Note: destinationFile must be Specified but should not Exist.
  342. //------------------------------------------------------------------------------
  343.  
  344. void ODSaveACopyOfDraft(Environment* ev, ODSession* session, ODDraft* draft, 
  345.                         PlatformFile* destinationFile);
  346.  
  347. //------------------------------------------------------------------------------
  348. // ODDocumentInfo
  349. //    Displays the document info dialog.
  350. //------------------------------------------------------------------------------
  351.  
  352. void ODDocumentInfo(Environment* ev, ODSession* session);
  353.  
  354. }    // End of extern "C" {
  355.  
  356. #endif
  357. // _DOCUTILS_
  358.